home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / misc / mmu_update / autodocs / memory.doc next >
Text File  |  1999-11-30  |  15KB  |  489 lines
  1. TABLE OF CONTENTS
  2.  
  3. memory.library/--Background--
  4. memory.library/CreateAdrSpace
  5. memory.library/DeleteAdrSpace
  6. memory.library/AllocVMPool
  7. memory.library/DeleteVMPool
  8. memory.library/AttachTask
  9. memory.library/DetachTask
  10. memory.library/AllocVMVec
  11. memory.library/FreeVMVec
  12. memory.library/LockVMVec
  13. memory.library/UnlockVMVec
  14. memory.library/--Background--                    memory.library/--Background--
  15.  
  16.     PURPOSE
  17.         The memory.library provides functions for memory allocation and
  18.         deallocation that are superior to those of the exec.library.
  19.  
  20.         The functions of this library will provide so called "virtual memory"
  21.         by using the mmu.library, memory that can be swapped to disk
  22.         transparently to the application. Hence, applications will be usually
  23.         able to allocate more memory than physically available.
  24.  
  25.         Certain access restrictions arise for memory allocated by the
  26.         memory.library. First, you can't access it in Forbid() or Disable()
  27.         state. Second, it can't be shared amongst different pools. You
  28.         must explicitly attach the tasks that should be able to access memory
  29.         from a given pool. Thus, you can't use this kind of memory for keeping
  30.         Os structures since they may be passed to different tasks for further
  31.         processing. Third, you MAY NOT access virtual memory in a situation
  32.         where file I/O would be impossible. That is, DO NOT access this mem
  33.         while:
  34.             - holding a lock on the dos.library handler lists
  35.             - disabling the filing system of the swap partition
  36.             - making the swapping exec.device unaccessible
  37.             - taking over the hardware
  38.         The mmu.library will try to detect such situations and will throw
  39.         a guru if that's possible. However, if it is not, these situations
  40.         will result in a dead-lock! Keep care!
  41.     
  42.  
  43.         This restriction can be somewhat weakened by the LockVMVec/UnlockVMVec
  44.         functions. By calling these functions, you can lock a given memory
  45.         vector in memory and hence, will be able access it WITHIN Forbid().
  46.         It returns a pointer to the physical location of that memory block
  47.         which must be used if that memory is passed to a different task or
  48.         other hardware components.
  49.  
  50.         This kind of "virtual memory" is of course some kind of a 
  51.         "poor man's solution" for implementing virtual memory. No exec
  52.         function will be patched and old programs will continue to work
  53.         without any change. The library is of course of limited or no use
  54.         at all for old programs since it doesn't redirect standard memory
  55.         allocation functions to their "virtual" counterparts. Thus, this
  56.         is a very "conservative" approach to overcome this limitation of
  57.         AmigaOs.
  58.  
  59.         A special "VMM/GigaMem" patch might be made available that uses
  60.         the functions of this library to provide virtual memory to every
  61.         task. However, since this CAN'T be fully compatible to old programs
  62.         and may, therefore, cause some compatibility problems. It should be
  63.         up to the user if she/he likes to install a patch like this or not,
  64.         but it should NOT the way how virtual memory enters AmigaOs, at 
  65.         least not now.
  66.  
  67.         The basic objects the memory.library handles is first the
  68.         "AddressSpace" object. It defines - as it says - an common 
  69.         address space for the tasks attachted to it. It is the memory.library
  70.         implementation of the mmu.library "context". Each address space can
  71.         be linked to as many tasks as you wish, but a task can be attached
  72.         to only one address space at a time.
  73.         The actual memory allocation is done from "VMPools". They are the
  74.         memory.library counterpart of the exec "memory pools". Each address
  75.         space may contain as many "VMPools" as you wish, but only tasks
  76.         attachted to the address space of the pool can use it.
  77. memory.library/CreateAdrSpace                    memory.library/CreateAdrSpace
  78.  
  79.     NAME
  80.         CreateAdrSpace    -    create a new address space.
  81.  
  82.     SYNOPSIS
  83.         BOOL CreateAdrSpace( );
  84.         d0
  85.  
  86.         BOOL CreateAdrSpace( VOID );
  87.  
  88.     FUNCTION
  89.         Build a new address space and attach the calling task to this
  90.         address space. 
  91.  
  92.     INPUTS
  93.         none.
  94.  
  95.     RETURNS
  96.         a true/false boolean success indicator.
  97.  
  98.     NOTES
  99.         This call will build a new mmu.library "Context" for the calling
  100.         task and will enter this context for this task. The task calling
  101.         this function should not be attachted to any other address space
  102.         or this task will fail. A task can be attached to one address 
  103.         space at a time only.
  104.  
  105.         This call will change the tc_Switch() and tc_Launch() function
  106.         pointers of the calling task.
  107.  
  108.     SEE ALSO
  109.         DeleteAdrSpace(), exec/tasks.h
  110.  
  111. memory.library/DeleteAdrSpace                    memory.library/DeleteAdrSpace
  112.  
  113.     NAME
  114.         DeleteAdrSpace    -    delete an address space.
  115.  
  116.     SYNOPSIS
  117.         DeleteAdrSpace( );
  118.  
  119.         DeleteAdrSpace( void );
  120.  
  121.     FUNCTION
  122.         This call deletes the address space of the calling task. It will
  123.         leave the private context build for this address space and will
  124.         enter the global context.
  125.  
  126.     INPUTS
  127.         none.
  128.  
  129.     RETURNS
  130.         nothing.
  131.  
  132.     NOTES
  133.         This call uses the CurrentContext() call of the mmu.library and
  134.         deletes this context. The task is then re-attachted to the global
  135.         common context. No virtual memory must be used at that time, nor
  136.         any other task may be attachted to this address space.
  137.  
  138.         It is safe to call this function if the calling task isn't attached
  139.         to any address space. Nothing will happen in this case.
  140.  
  141.     SEE ALSO
  142.         CreateAdrSpace(), mmu.library/CurrentContext()
  143.  
  144. memory.library/AllocVMPool                            memory.library/AllocVMPool
  145.  
  146.     NAME
  147.         AllocVMPool    -    create a pool of virtual memory.
  148.  
  149.     SYNOPSIS
  150.         pool = AllocVMPool( reqments, attributes );
  151.         d0                    d0          d1
  152.  
  153.         VMPool * AllocVMPool( ULONG, ULONG );
  154.  
  155.     FUNCTION
  156.         Creates a memory pool for virtual memory and adds the calling task
  157.         to the list of tasks that can safely use this pool.
  158.  
  159.     INPUTS
  160.         reqments    -    an exec style memory attributes flags field.
  161.                 This defines the memory type the pool will be taken from,
  162.                 not ANY implications about the logical addresses asssigned
  163.                 to the memory allocated from that pool. Thus, if you call
  164.                 LockVMVec() later on, that vector will be mapped to the
  165.                 memory described by the reqments above.
  166.  
  167.                 The following bits, defined in exec/memory.h will be 
  168.                 ignored:
  169.  
  170.                 MEMF_PUBLIC        -    as the pool is always private in 
  171.                     this sense.
  172.  
  173.                 MEMF_CLEAR        -    as this flag must be specified 
  174.                     individually when allocating memory from the pool.
  175.  
  176.         attributes    -    special attribute flags.
  177.  
  178.                 VMEMF_PRIVATE    -    make the memory in the pool invalid
  179.                     to other tasks.
  180.  
  181.                 VMEMF_PROTECT    -    protect the underlying MMU context.
  182.  
  183.                 VMEMF_NONCACHE    -    mark the memory in the pool 
  184.                     explicitly as noncacheable 
  185.                     (defaults to the cache type of the physical memory)
  186.  
  187.                 VMEMF_PRECISE    -    mark the memory in the pool as
  188.                     requiring the precise exception model.
  189.                     (only for special MMUs, not available in general)
  190.                     Implies VMEMF_NONCACHE
  191.  
  192.                 VMEMF_SERIALIZED-    mark the memory as serialized non-
  193.                     cacheable.
  194.                     (only for special MMUs, not available in general).
  195.  
  196.         RETURNS
  197.             A handle to the pool or NULL in case of failure. The calling
  198.             task will be prepared to use the memory in the pool.
  199.  
  200.         NOTES
  201.             To use this call, a private address context must have been
  202.             build before.
  203.  
  204.         SEE ALSO
  205.             CreateAdrSpace(), DeleteVMPool(), exec/memory.h
  206.                 
  207. memory.library/DeleteVMPool                        memory.library/DeleteVMPool
  208.  
  209.     NAME
  210.         DeleteVMPool    -    Delete a virtual memory pool.
  211.  
  212.     SYNOPSIS
  213.         result    =    DeleteVMPool( pool);
  214.         d0                          a0
  215.  
  216.         BOOL DeleteVMPool (VMPool *);
  217.  
  218.     FUNCTION
  219.         Deletes the given virtual memory pool in question, releases the
  220.         memory occupied by the pool and the release the used space on disk.
  221.  
  222.     INPUTS
  223.         pool    -    a handle to a VMPool as created by AllocVMPool. 
  224.             Passing in NULL is safe.
  225.  
  226.     RESULTS
  227.         A boolean that indicates whether some memory in the pool is
  228.         still allocated. Can be usually ignored but is useful for
  229.         debugging.
  230.  
  231.     NOTES
  232.  
  233.     SEE ALSO
  234.         AllocVMPool()
  235.  
  236. memory.library/AttachTask                            memory.library/AttachTask
  237.  
  238.     NAME
  239.         AttachTask - attach a task to the address space of the calling task.
  240.  
  241.  
  242.     SYNOPSIS
  243.         result = AttachTask( task);
  244.         d0                     a1
  245.  
  246.         BOOL AttachTask(struct Task *);
  247.  
  248.     FUNCTION
  249.         To allow another task sharing the same address space than the calling
  250.         task, this new task must be attached to the common address space
  251.         with this call. Afterwards, the task passed in the parameter may
  252.         use the same virtual memory pools as the calling task.
  253.  
  254.     INPUTS
  255.         task    -    The task to be added to the allowed tasks for the
  256.             address space of the calling task.
  257.  
  258.     RETURNS
  259.         a boolean indicating whether it was possible to add the task to
  260.         the adrspc. 
  261.  
  262.     NOTES
  263.         It is intentionally not possible to add tasks to an address space
  264.         of a different task than the calling one.
  265.         
  266.     SEE ALSO
  267.         DetachTask()
  268.  
  269. memory.library/DetachTask                            memory.library/DetachTask
  270.  
  271.     NAME
  272.         DetachTask - remove the calling task from its address space.
  273.  
  274.     SYNOPSIS
  275.         DetachTask( );
  276.  
  277.         VOID DetachTask( VOID );
  278.  
  279.     FUNCTION
  280.         Remove the calling task from its address space and let it enter
  281.         the common context again. The address space itself will continue
  282.         to exist.
  283.  
  284.     INPUTS
  285.         none.
  286.  
  287.     RETURNS
  288.         nothing.
  289.  
  290.     NOTES
  291.         The current task is, after calling this function, no longer allowed
  292.         to use any virtual memory allocated by the memory.library pool
  293.         functions of that pool.
  294.  
  295.         The only use of this function is to pass an address space from a
  296.         creator task to its children, i.e. by first calling CreateAdrSpace,
  297.         then launching the child process, attaching the child process to
  298.         that address space and removing the creator task from that pool.
  299.         It's then up to the children to remove themselves from that address
  300.         space on exit and to delete the address space created this way.
  301.  
  302.         It is safe to call this function if the current task isn't attached
  303.         to any address space. Nothing will happen in this case.
  304.  
  305.     SEE ALSO
  306.         AttachTask(), CreateAdrSpace()
  307.  
  308. memory.library/AllocVMVec                            memory.library/AllocVMVec
  309.  
  310.     NAME
  311.         AllocVMVec    -    allocate virtual memory from a pool.
  312.  
  313.     SYNOPSIS
  314.         mem = AllocVMVec( pool, bytesize, flags);
  315.         d0                  a0    d0          d1
  316.  
  317.         void * AllocVMVec( Pool *, ULONG, ULONG);
  318.  
  319.     FUNCTION
  320.         This function allocates memory from a given virtual pool.
  321.  
  322.     INPUTS
  323.         pool    -    The pool to allocate the memory from.
  324.  
  325.         bytesize-    The size of the memory required. This might be larger
  326.             than the amount of physical memory available, but you won't
  327.             be able to access the complete memory block at once or
  328.             to lock it in memory.
  329.  
  330.         flags    -    allocation flags. The following flags are used:
  331.     
  332.             MEMF_PUBLIC        The returned memory will be public, i.e.
  333.                             non-virtual.
  334.  
  335.             MEMF_REVERSE    The memory will be allocated from the pool
  336.                             in reverse order.
  337.  
  338.             MEMF_CLEAR        The memory will be wiped out before it is 
  339.                             passed back.
  340.  
  341.             All other memory relevant flags as the caching mode and whether
  342.             the memory is in CHIP or in FAST memory is determined by the
  343.             flags used when allocating the pool.
  344.  
  345.     RETURNS
  346.         the memory block allocated or NULL for failure. If the calling
  347.         task is a process, the pr_Result2 field will be set to 
  348.         ERROR_NO_FREE_STORE (103).
  349.  
  350.     NOTES
  351.         This call may break a Forbid() state. It may swap out pages of
  352.         virtual memory if necessary.
  353.  
  354.         The returned memory will be aligned to at least one longword,
  355.         the size might be rounded somewhat, but will at least contain
  356.         the number of bytes specified by the argument.
  357.  
  358.         To be able to allocate memory from the pool, the calling task
  359.         must have been the creator of that pool or must have been added
  360.         to the list of allowed tasks for that pool with AttachTask().
  361.  
  362.     SEE ALSO
  363.         FreeVMVec(), AttachTask(), exec/memory.h
  364.  
  365. memory.library/FreeVMVec                            memory.library/FreeVMVec
  366.  
  367.     NAME
  368.         FreeVMVec    -    allocate virtual memory from a pool.
  369.  
  370.     SYNOPSIS
  371.         FreeVMVec( pool, mem);
  372.                    a0    a1
  373.  
  374.         VOID FreeVMVec( Pool *, void *);
  375.                         a0        a1
  376.  
  377.     FUNCTION
  378.         This function returns memory allocated from the pool.
  379.  
  380.     INPUTS
  381.         pool    -    The pool the memory was taken from.
  382.  
  383.         mem        -    The memory vector to free. No byte size is passed,
  384.                 the size is implicit. It is safe to pass NULL here. No
  385.                 action is performed in this case.
  386.  
  387.     RETURNS
  388.         none.
  389.  
  390.     NOTES
  391.         This call may break a Forbid() state. It may swap in pages of
  392.         virtual memory if necessary.
  393.  
  394.         To be able to call this function, the calling task must either
  395.         the creator of the pool, or any other task that has been attached
  396.         to the pool with AttachTask().
  397.  
  398.     SEE ALSO
  399.         AllocVMVec(), AttachTask()
  400. memory.library/LockVMVec                            memory.library/LockVMVec
  401.  
  402.     NAME
  403.         LockVMVec    -    Lock a memory vector in memory.
  404.  
  405.     SYNOPSIS
  406.         phmem = LockVMVec( pool, mem);
  407.         d0                    a0      a1
  408.  
  409.         void * LockVMVec( Pool *, void *);
  410.  
  411.     FUNCTION    
  412.         This function locks the specified vector in memory such that it
  413.         is guaranteed to be non-virtual and accessable by all tasks and
  414.         to all Os functions. The physical address of that memory is
  415.         returned as it should be used to "the outher world".
  416.  
  417.     INPUTS
  418.         pool    -    a handle to the memory pool the memory was taken from.
  419.  
  420.         mem        -    the pointer to the memory vector in question. This is
  421.             the logical address returned by AllocVMVec, not a physical
  422.             address.
  423.  
  424.     RETURNS
  425.         a pointer to the location of that memory block in physical memory
  426.         or NULL if not enough physical memory is available to swap in that
  427.         page in question.
  428.  
  429.     NOTES
  430.         The calling task must be either the task that created the pool,
  431.         or any other task that was attachted to that pool.
  432.  
  433.         Using this call turns effectively private virtual memory in
  434.         standard exec memory. Therefore, not too many virtual pages should
  435.         be locked and this call should be avoided in general unless you
  436.         need to swap in the virtual memory in question TEMPORARILY. Call
  437.         UnlockVMVec() as soon as possible to allow swapping out of the
  438.         memory again.
  439.  
  440.         Due to the memory paging of the MMU, this call swaps actually more
  441.         than the desired memory block in.
  442.  
  443.         This call may break a forbid state, it MAY fail if not enough
  444.         physical memory is available.
  445.  
  446.         This call nests - each call to LockVMVec() must be matched by one
  447.         call to UnlockVMVec().
  448.  
  449.     SEE ALSO
  450.         UnlockVMVec()
  451.  
  452. memory.library/UnlockVMVec                            memory.library/UnlockVMVec
  453.  
  454.     NAME
  455.         UnlockVMVec    -    Lock a memory vector in memory.
  456.  
  457.     SYNOPSIS
  458.         UnlockVMVec( pool, mem);
  459.                      a0       a1
  460.  
  461.         VOID UnlockVMVec( Pool *, void *);
  462.  
  463.     FUNCTION    
  464.         This function unlocks a memory block and re-allows swapping out
  465.         of that memory block.
  466.  
  467.     INPUTS
  468.         pool    -    a handle to the memory pool the memory was taken from.
  469.  
  470.         mem        -    the pointer to the memory vector in question, the
  471.             logical address.
  472.  
  473.     RETURNS
  474.         nothing.
  475.  
  476.     NOTES
  477.         The calling task must be either the task that created the pool,
  478.         or any other task that was attachted to that pool.
  479.  
  480.         This call turns locked memory again in virtual memory and allows
  481.         the library to swap it out again.
  482.  
  483.         DO NOT use the physical address returned by LockVMMem() again
  484.         after having called this function.
  485.  
  486.     SEE ALSO
  487.         LockVMVec()
  488.  
  489.